Text File | 1990-03-13 | 34.6 KB | 370 lines | [04] ASCII Text (0x0000)
DEBUGGING DECLARATION ROMS
Through system software, the Macintosh can read the declaration ROMs in NuBus and pseudo-NuBus slots, like those in the Macintosh SE/30. This article tells you what you must know about NuBus addressing and the structure of correct declaration ROMs to successfully debug the ROM. It walks you through the structure of an example declaration ROM and gives common errors and strategies for debugging declaration ROMs.
The Slot Manager's flexibility in providing a layer between the hardware and higher-level software benefits developers and customers alike. Users can easily expand the Macintosh II family and the Macintosh SE/30 with additional hardware that goes in slots. The Macintosh card architecture lets them plug new cards into the Macintosh without worrying about using the right slot, setting dip switches, or running system configuration software. As a developer, you may need to know more about the architecture that makes this self-configuring environment possible.
THE SLOT MANAGER AND DECLARATION ROMs
Part of the Macintosh operating system, the Slot Manager can find the ROM on each expansion card installed in a system and identify the card's special capabilities. It makes use of predefined data structures called slot Resources (sResources) to initialize and configure a card and report the card's location. Each card installed in a Macintosh expansion slot needs a declaration ROM, also known as a configuration ROM, with information for using the card's hardware. The expansion hardware could be as simple as a memory card that needs to publish its address ranges or as complicated as a video card with initialization code, a driver, and declaration data.
In addition to letting the system determine what hardware is available, the Slot Manager frees applications from being dependent on a particular type of hardware. In other words, the Slot Manager helps insulate an application from the hardware by being able to locate underlying, intermediate driver software that will know about and talk to the specific hardware. The application can be free of the details and need only deal with higher-level functions. The degree of insulation depends on the software and data structures in the declaration ROM.
The Slot Manager:
o locates and lists the cards with declaration ROMs.
o defines a uniform structure for information in the declaration ROM and a set of library routines to access the information.
o includes routines to allow host applications to transparently access information in the ROMs without regard to NuBus or byte lanes.
o allows ROM initialization code to run on the host CPU during the host's startup sequence.
o allows cards to have drivers from their declaration ROMs loaded into the host CPU.
o initializes and manipulates the parameter RAM on the host CPU for the card during startup.
When applications are insulated from particular hardware implementations, they don't have to be revised for each new version of a vendor's board, or even for compatible boards made by competitors. Besides reducing maintenance work for the developer, information hiding of this sort saves wear and tear on customers.
Suppose a customer owns an application and a card and happens to buy another board, from the same or a different vendor, with even slightly different hardware. The difference might be a change in address or meaning of some register or memory location. The customer has to mix and match applications or drivers or INITs to boards. This is not very Macintosh-like, and the board manufacturer is sure to be savaged by the customers and the press. Matching various card-specific versions of software and different revisions of hardware can be a headache for distributors and dealers. Including card-specific software on each card's ROM in a universally accessible structure greatly simplifies installation and maintenance.
Using sResources
Don't confuse sResources on expansion cards with standard Macintosh resources. The small s indicates a slot resource as opposed to a real Macintosh resource. Although related conceptually, sResources are different and may contain anything from code to data-for example, icons, special fonts, or vendor-defined data. In fact, feel free to substitute "data structure" for "sResource" as you read.
Each card has one special sResource called a board sResource and usually one additional sResource for each function the card can perform, although additional supporting sResources are possible. An sResource affiliated with a function is called a functional sResource and gives information about that particular function, usually to high-level applications interested in accessing the function.
Most cards perform only one function. For example, a modem card might perform only a modem function, a video card might just do video, and so on. These cards would have only one functional sResource, along with the required board sResource. However, it is possible to build a multifunction expansion card-a card with a parallel, serial, and modem port, for example. In this case, the card's declaration ROM would have three functional sResources-one each for the card's functions. In addition to other, optional sResources, it would also have the required board sResource.
A high-level program may need to be able to find and use certain kinds of hardware in the Macintosh slots. For example, QuickDraw works with video cards made by different vendors. QuickDraw finds each video card by looking for the card's functional sResource that says it can do QuickDraw-compatible video.
An Example Declaration ROM
As far as the Slot Manager is concerned, at the startup scan of the cards a valid declaration ROM must have proper structures for the format block, sResource directory, and the board sResource. If any of these structures is in error, the Slot Manager marks the slot as empty, and no Slot Manager calls to that slot will work. Though other sResources or data structures may have errors, the Slot Manager doesn't check them at startup. These errors will show up during later calls to the Slot Manager by applications, INITs, drivers, and so forth.
We will look at these key structures in an example declaration ROM and will discuss some common errors developers make. The sample skeleton ROM has the required board sResource and one functional sResource.
The ROM can be divided into four major structures: the sResource directory, functional sResource, board sResource, and format block, as shown in the illustration. Let's look at these structures in more detail.
The sResource DIRECTORY
The source code begins with some includes and equates, followed by the sResource directory. A directory is a list of the sResources in the ROM. In the example, we have two sResources, the required board sResource and one functional sResource. The directory looks like this:
_sRsrcDir OSLstEntry sRsrcBoard,_sRsrcBoard
;References Board sResource.
OSLstEntry sRsrcFun,_sRsrcFun
;References functional sResource.
DatLstEntry endOfList,0
;End of the list.
The OSLstEntry and DatLstEntry items are assembler macros, defined in the MPW ROMEqu.a file. These macros make creating declaration ROMs easier, since most declaration ROM structures fall into two different formats:
o an ID byte followed by three bytes representing a 24-bit offset or
o an ID byte followed by a 24-bit data value
A directory contains both of these formats. The first format is used for all sResource entries in a directory. Each sResource entry consists of one byte containing the sResource identification number, and three bytes containing the offset to the sResource itself.
The offset list entry (OSLstEntry) macro is used to conveniently calculate and fill in these types of entries. It takes two arguments: the ID byte and a label designating the destination. The macro puts the first argument as is into the high byte, calculates the 24-bit signed offset value to the destination label, and puts it into the next three bytes. In our example, the first entry of the directory looks like this:
The _sRsrcDir label designates the start of the directory. This label is needed because the offset to the directory will be calculated later. The first argument of the macro, sRsrcBoard, is equated to 1 (in the equates near the top of the source code file), and so a $01 will be put into the first byte. The second argument, _sRsrcBoard, is the label designating the start of the board sResource. The macro calculates the offset from the present point in the macro to the label and puts the resultant offset in the next three bytes. The _sRsrcBoard structure is $000C bytes away from the directory entry, so the offset is $000C. Putting them together, the complete directory entry for the board sResource looks like this in hexadecimal:
$01000C
A similar calculation for the functional sResource is done with the offset from the directory to the _sRsrcFun label.
The second format is used in many places in declaration ROMs. It is commonly used for the end-of-list entry, which marks the end of the list of directories and sResources. This entry always has an ID byte value of $FF followed by three bytes of zero. It can also be used to hold small pieces of data that fit into three bytes or less.
It is convenient to use the data list entry (DatLstEntry) macro for these types of entries. DatLstEntry is similar to OSLstEntry but simpler. It takes two arguments: the ID byte and the desired data value. It puts the first argument into the high byte and the data value into the next three bytes.
SResources in General
Before looking at our example sResources, let's examine the structure of sResources in general. Every sResource includes an sRsrc_Type entry whose fields identify the sResource. Applications and drivers use the sRsrc_Type entry of each sResource to identify it and the function it performs.
The sRsrc_Type entry is comprised of an ID byte (always a $01), followed by an offset to the sResource type format. For this discussion, we will only look at the Apple defined format for the type format entry, indicated by the leading bit being a zero, since virtually all developers use it.
The sResource type format is a 64-bit value, separated into four fields of 16 bits each. The entry looks like this:
The type format fields have constant, fixed values for the board sResource, so let's look at the values for the more general case of functional sResources. The type format is hierarchical in nature, and the four fields can be considered to be "nested" under each other, with the Category being at the top of the hierarchy. While some of the fields have been predefined, new values can be and often are defined to suit developers' products.
A board can perform broad categories of possible functions, which are represented by the Category field of the type format. Within each Category are subset types that are represented by the cType value. Nested farther in the hierarchy are subset software driver identifiers (the DrvrSW value). Finally, under each DrvrSW
entry, there are hardware identifiers (the DrvrHW value). The hierarchical relationship looks like:
Category
cType
DrvrSW
DrvrHW
A given Category can have multiple cType interfaces for it, and each of those cTypes can have its own nested, underlying software interfaces. Many different pieces of hardware can belong to a given software architecture. Equates for many categories have been already defined, such as Display, Network, Communication, and CPU. Further, subtypes for some of these common categories have been defined, as well as software interfaces to go with some subtypes.
Let's see how this works with a common family of cards: video cards. A category for display functions has been defined (CatDisplay EQU $0001). Under it, a subtype for video displays has been defined (TypVideo EQU $0000). Since Apple has defined a driver and firmware interface for video display cards that are QuickDraw compatible, there is a software driver definition as well (DrSWApple EQU $0001). Now let's say a developer wants to make a QuickDraw-compatible video card - the Amalgamated VaporWare Widget video board. The developer gets a hardware identifier from .Developer Technical Support-let's say DTS assigns the developer DrHwWidget EQU $4321-and creates a functional sResource with an sRsrc_Type of
CatDisplay EQU $0001
TypVideo EQU $0000
DrSwApple EQU $0001
DrHwWidget EQU $4321
or in the complete type format:
0001000000014321
Now QuickDraw will recognize the card, because it looks for type formats that match CatDisplay/TypVideo/DrSwApple. During the search, QuickDraw will only look for a match down to its software architecture level and will mask off the hardware identifier. It does not care about the hardware identifier, because it knows the driver will deal with the underlying hardware. Notice that even though the first three entries in the type format will be the same for all QuickDraw-compatible video cards, the different hardware identifiers will make the entries unique. This is useful for the driver of the Widget card, which very much cares about the underlying hardware. It will want to locate the card and will do so by doing a match of the whole type format, including the hardware identifier.
Developers can take advantage of this if they want to have applications use their software/hardware architecture. By publishing the software interface and type format values, a developer can make a board that others can write applications for.
Besides the sRsrc_Type entry, sResources must also have a name entry (sRsrc_Name), which contains an ID byte (always $02), followed by an offset to a null-terminated string (a C string). In addition to these, the board sResource must have a board ID value (BoardId). All other entries defined for sResources and the board sResource are optional.
Now, let's take a look at the two sResources in detail.
The Board sResource
Like the directory entries, our board sResource uses the macros we discussed earlier to calculate and fill in the various entries. Labels such as sRsrcType and sRsrcName are defined in the MPW ROMEqu.a file. Others, such as the board ID, are in the declaration ROM source code. The first part of our board sResource looks like this:
The _sRsrcType entry for the board sResource points to the board sResource type format. The type format is always the same for the board sResource-that's how the board sResource is identified. The type format for the board sResource always has this definition:
_BoardType DC.W CatBoard; ;ALWAYS $0001 for bd sResource
DC.W TypBoard; ;ALWAYS $0000 for bd sResource
DC.W DrSwBoard; ;ALWAYS $0000 for bd sResource
DC.W DrHwBoard; ;ALWAYS $0000 for bd sResource
Put together into the full 64 bits, it looks like this:
$0001000000000000
The _sRsrcName entry points to the name string (a C string), which should be the official product name of the board:
_BoardName DC.L 'OFFICIAL PRODUCT NAME'
;The name of the Board - should be official product name
(At the beginning of the source code, there is a STRING C directive, to automatically generate c strings.)
After the name comes the required board ID, which, being a 16-bit value, can be filled in using a DatLstEntry macro. Board IDs are assigned by Macintosh DTS. To get board ID, contact Macintosh DTS with the following information:
o the company name and address (mailing and electronic addresses, if possible)
o the name of the person in the company responsible for the board (and a phone number, if possible)
o the functions the board will perform
o the official product name for the board (or a code name)
o whether or not the board will have a software driver other than one that has been predefined (like Apple's video driver)
o whether or not the driver will be in ROM
DTS will assign the board ID and any necessary functional sResource information. This information goes into a database, which is kept strictly confidential. There is a HyperCardr stack on the Developer Services CD and on AppleLink that makes sending in this information easier.
Next, the board sResource contains an entry for the primary initialization code. We have defined one, but it is in a separate file called PrimaryInit.a, which is referenced with an INCLUDE directive:
The following is optional vendor data. It is up to the developer to decide what, if anything, goes in the VendorInfo entries. This example shows the way Apple typically uses the vendor information ;entries.
OSLstEntry PartNum,_PartNum ;References ;the Part ;Number.
DatLstEntry endOfList,0 ;End of the ;list.
_VendorId DC.L 'COMPANY NAME' ;The Vendor ;Id. Most ;vendors use
;company name
_RevLevel DC.L 'Release-1.0' ;The Revision ;Level
_PartNum DC.L '12-3456' ;The Part ;Number
The Functional sResource
In our example, our card has only one function, so our ROM has just one functional sResource. For this example, we have defined a nonexistent set of Category, subtype, software, and driver identifiers, which normally would be replaced by the ones assigned by DTS. The functional sResource entry looks like this:
The type format for our fictional function looks like this:
_FunType DC.W CatExCat ;<Category>
DC.W TypExTyp ;<Type>
DC.W DrSwExSw ;<DrSw>
DC.W DrHwExHw ;<DrHw>
The sRsrc_Names for functional sResources follow a convention of concatenating the equates for the sRsrc_Type but stripping off the prefixes and separating the type format fields by underscore characters. Since our type is CatExCat/TypExType/DrSwExSw/DrHwExHw, the sRsrc_Name becomes:
_FunName DC.L 'ExCat_ExType_ExSW_ExHW'
The driver directory identifies the type of driver and the driver itself. In the example, the driver is compatible with the Macintosh OS but contains Motorola 68020 code. The driver itself is in a separate file and is referenced by an INCLUDE directive.
The hardware device ID field (HWDevID) is optional and defined by the vendor. It can be used to indicate that an sResource is associated with a particular piece of hardware. This would be used in the case of cards that had multiple "hardware areas"-say, multifunction cards-that could be considered to be separate hardware devices. The field could be used to group certain sResources with the various devices. In this case, the functional sResources would have different HWDevID values depending on which hardware device on the card they describe.
For example, you have a card with two serial ports, which you label port 1 and port 2. You have three functional sResources-an asynchronous serial sResource, a MIDI sResource, and a network sResource. Let's say the async serial sResource is assigned to port 1. It is assigned HWDevID=1. Now let's say the network sResource can only be used with port 2. It is assigned HWDevID=2. Similarly, the MIDI sResource can only be used on port 1. It will also be assigned HWDevID=1. Now, by looking at the HWDevID fields, a driver or card software can tell which piece of hardware it is using in case different hardware on the card has different characteristics it must handle. If an sResource does not describe a hardware device, then the HWDevID field may be omitted.
The MajorBaseOS , MinorBaseOS, MajorLength, and MinorLength fields describe where the hardware area starts and how large it is. For example, a video sResource might have the MinorBaseOS be an offset to the starting address of the video frame buffer. The MinorLength field would tell how large it is. Other cards might use the MinorBaseOS to indicate where its hardware control registers are.
Use Major vs. Minor depending whether you want to reference the area using super slot space or NuBus slot space addresses.
In the example, let's say this function has some RAM memory in NuBus slot space that we would like to reference:
_MinorBase DC.L defMinorBase ;RAM Offset
_MinorLength DC.L defMinorLength ;RAM length
The Format block
Declaration ROMs are recognized by the presence of the ROM's format block, which occupies the highest address of the ROM's slot address space. This is our example format block:
The first entry calculates the offset to the beginning of the directory, using the directory label. This must be a signed 24-bit value.
The ROM size, revision level, format, test pattern, and reserved values are declared in the source and in the included MPW ROMEqu.a file. The CRC value can be generated and patched in by utilities such as MPW tools. Apple supplies two MPW tools on the Developer Services CD and AppleLink called Data and CRC. Data takes the assembled source code file, strips off the CODE 0 resource, and puts the CODE 1 segment (now the actual ROM image) into a data file. This will be convenient for later downloading to a ROM burner. The CRC tool takes the ROM image, calculates the CRC value, and inserts it into the proper place.
The last field in the block is the ByteLanes field, a signature byte that identifies which of the four NuBus byte lanes the ROM image appears on. The Slot Manager attempts to read a valid value in each of the four byte lanes at the end of the slot space. If the Slot Manager is unable to read a valid field, then an error is posted for this slot. If a valid ByteLanes value is read, this information is used to confirm a special test pattern, and perform a ROM validity check. If all verification passes, then the system can utilize the offset to the sResource directory. Note that the Slot Manager attempts to read the format block in both the 1 MB and 16 MB NuBus slot spaces. If any of these verification checks fails, the slot is marked as empty or invalid, and all Slot Manager calls to that slot will return errors.
Potential Problems
Now that we've covered the source code to the example ROM, let's look at some common problems developers experience. When trying to assemble the source code, if one or more of the arguments to the OSLstEntry or DatLstEntry macro is incorrectly defined or just left out, you will get an assembler error in the middle of the macro, and the assembler will complain with the error message:
Invalid arithmetic operation on relocatable id
This message was generated as a result of the assembler's inability to resolve one of the two arguments to the macro. If you get this error, check both arguments and make sure the labels are correctly defined. The first argument must be equated to something in your source or the development system include files, and the second argument must be a label that exists in the source code. Please be aware that some of the predefined equates (in the assembler include files) changed from MPW 2.0 to 3.0. For instance, to improve readability, some IDs had the underscores in the middle removed (Cat_Board became CatBoard in a directory, for example).
Another error can arise from a bug in the macro defined up to and including MPW version 3.0. Most declaration ROM sources are arranged in a sequence like ours: the directory comes first in the source code (and so is lowest in memory), followed by the sResources, and finally the format block, which is at the very end of the source listing.
Structures referenced by sResources are usually defined after the sResources. That is, usually things are referenced in a forward manner and come later in the source code.
Laying out the sResources this way, the macro works fine. However, if you want to have the macro calculate a negative offset to a structure, to reference something that comes earlier in the source code, you may run into trouble. The following macro definition:
MACRO
OSLstEntry &Id,&Offset
DC.L (&Id<<24)+&Offset-*
ENDM
can be fixed by changing it to:
MACRO
OSLstEntry &Id,&Offset
DC.L (&Id<<24) ++ ((&Offset-*) ** $00FFFFFF)
ENDM
This correctly masks off the high byte of the 24-bit offset and thus allows the full range of positive as well as negative offsets to structures.
Often, the source code to the ROM will build, but because of errors in the declaration ROM data structures, the Slot Manager will fail to recognize the ROM, or will generate errors while looking at certain structures. When this happens, looking at the error generated and manually disassembling the ROM will usually find the error. This requires understanding how the ROM appears from a debugger.
Dissembling the ROM
Declaration ROMs often occupy only one or two of the four NuBus byte lanes, meaning you have to translate your assembly listing by hand. This is because the assembler generates the listing as though the ROM occupies all four byte lanes (that is, as though it would reside in RAM). To translate from the ROM listing to the actual physical addresses the ROM occupies requires knowledge of byte lanes, which are often misunderstood.
The NuBus bus width is 32 bits, or, very importantly, four bytes. Think of each group of four bytes as a chunk. A chunk on the NuBus would look like this:
The four bytes of each chunk are identified by the byte number as shown in the illustration. Byte number 3 on the NuBus side-the most significant-contains NuBus address and data bits 31-24, byte number 2 contains A/D bits 23-16, byte number 1 contains A/D bits 15-8, and byte number 0-the least significant-contains A/D bits 7-0. Bytes whose address modulo 4 equals 0 are carried on byte number 0, those whose address equals 1 are carried on byte number 1, whose address equals 2 are carried on byte number 2, and whose address equals 3 are carried on byte number 3.
This address-to-byte-number mapping is conveniently set up for an Intel-type processor, which carries the most significant bits on a higher numbered address. The Macintosh uses a Motorola type processor, which has the most significant bits on a lower numbered address. In order to preserve consistency of byte addressing, Apple does byte swapping from the NuBus to the Motorola 680x0 CPU.
To see this more clearly, let's expand the byte lanes diagram from the address space chapter of Designing Cards and Drivers for the Macintosh Family.
The diagram looks quite complicated. Fortunately, once you understand the key concepts, it's not. The addressing of bytes within a chunk is in reverse order on the NuBus and 680x0 sides. However, the address range of a chunk is the same when viewed from the NuBus or 680x0 side. The hardware interface between the CPU on the motherboard swaps the bytes of a chunk when going to and from the NuBus.
Now that we understand the byte and address translation between our CPU and the NuBus, let's look at part of our assembled ROM listing. The best place to start is at the format block at the "top" or highest physical address of the ROM, since this is where the Slot Manager starts looking at startup time to find valid declaration ROMs. Assembled, the format block looks like:
The Slot Manager will start scanning from the highest address, looking for a ByteLanes value. From there, it will look for confirmation of the ByteLanes value by looking for the reserved values, the test pattern, proper format, and revision values, down to the CRC calculation. If there is a problem with the ByteLanes value or the way the card has been built, this Slot Manager check will fail. At this point, you should load up a debugger and look at the format block. Assuming the board is in slot $B, the above format block (residing on byte lane 3) might look like this in memory (as seen from MacsBug):
The lowest address is at the upper left, and the highest address is at the lower right, with increasing addresses going from left to right. Note that the MacsBug listing shows an example CRC value ($9D8634FE) that was calculated and patched in after the ROM was assembled.
Slot Manager Errors
During evaluation at startup or in response to application/driver Slot Manager calls, a number of errors can be returned by the Slot Manager. Often this is due to an incorrect ByteLanes value or bad sResources. The error returned usually helps to narrow down the problem. You can look at the error, then manually track through sResources in the ROM. This requires disassembling and "playing Slot Manager" much as we did above. Drawing a diagram like the one in the front of the article with the addresses and values can often help. However, please note that many Slot Manager calls make other Slot Manager calls, and the error returned may reflect an error returned by one of those calls.
If an error or crash occurs in the ROM before a debugger is loaded (during the primary initialization routine, for example), you can defer the driver or primary initialization until after the boot process has begun and a debugger has been loaded. Do this by first making stubs for the driver and/or primary initialization, or deleting them entirely. Then run them from a high-level application, which can have the primary initialization or drivers in the application or possibly in separate files.
In order to keep the driver from being loaded until after the boot, you might have to temporarily change the functional sResource's type format. This is needed in the case of video boards, for example, since the startup code looks specially for video boards, runs their primary INITs, and opens the drivers. In this case, change the sRsrc_Type to something other than CatDisplay, TypVideo, DrSwApple so that the start code won't identify the video display function. Changing CatDisplay to CatNonsense EQU $0000 would do the trick.
Summary
Declaration ROMs store system-recognizable structures as well as vendor-specific data. Debugging declaration ROMs is complicated by the fact that the declaration ROM sits on the other side of the Nubus, and you have to translate the information you get. But using the techniques discussed in this article should make building, interpreting, and debugging declaration ROMS a little easier.
---------------
Mark Baumwell is a low-level O/S sort of guy. He started with Apple in 1981 after a stint with Zilog as a test engineer.
After three years in the Lisa division, Mark made the move to Macintosh DTS where he has fulfilled his lifelong dream of being
a firefighter. He professes to be "outdoorsy," and getting an airplane pilot's license is his current passion. He claims that nothing we could say would sully his reputation more than it has already been. We tried, but Apple Legal wouldn't approve it. Would
